.TH E1432_SET_OCTAVE_MEAS 3 E1432
.SH NAME
.nf
e1432_set_octave_meas \- Set Octave measurement on/off state
e1432_get_octave_meas \- Get Octave measurement on/off state
.IX e1432_set_octave_meas(3) 3
.IX e1432_get_octave_meas(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_set_octave_meas(E1432ID hw, SHORTSIZ16 ID,
                                 SHORTSIZ16 octave_meas)
SHORTSIZ16 e1432_get_octave_meas(E1432ID hw, SHORTSIZ16 ID,
                                 SHORTSIZ16 *octave_meas)
.cE
.SH DESCRIPTION

\fIe1432_set_octave_meas\fR turns Octave measurements on/off for the
modules(s) selected.

\fIe1432_get_octave_meas\fR returns the Octave measurment on/off state of
the modules(s) selected into a memory location pointed to by \fIoctave_meas\fR.

This parameter is a "global" parameter.  It applies to an entire
module rather than to one of its channels.  The \fIID\fR parameter is
used only to identify which module the function applies to, and all
channels in that module will report the same value for this parameter.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fIID\fR is either the ID of a group of channels that was obtained
with a call to \fIe1432_create_channel_group\fR, or the ID of a single
channel.
It is used to determine which module(s) in \fIhw\fR to set/query.

\fIoctave_meas\fR must either
\fBE1432_OCTAVE_MEAS_OFF\fR, to turn Octave measurements off,
or \fBE1432_OCTAVE_MEAS_ON\fR, to turn Octave measurements on.

Octave measurements can only be run on \fBE1433\fR modules with the
\fB1D1\fR "Real Time Octave" option installed.
Error \fBERR1432_OPTION_NOT_INSTALLED\fR is returned when the measurement
is started if the \fB1D1\fR option is not installed
if input channels are enabled.
Error \fBERR1432_OCTAVE_VS_MODULE_TYPE\fR is returned when the measurement
is started if the the module is not an \fBE1433\fR module
if input channels are enabled.

For Octave measurements to be run,
the clock frequencey must be set to 65536 by \fIe1432_set_clock_freq\fR.

Octave measurements utilize a special SCA DSP downloadable,
\fCsoct.bin\fR, which must either be located in \fC/opt/e1432/lib/\fR
(or \\HPE1432\\LIB\\ on PC systems)
if the \fIhwinstall (1)\fR program was used to download the 96000 firmware
or be in the same location as the 96000 firmware file
if the \fIe1432_install\fR function is used to install the 96000 firmware.
Alternatively, the \fIe1432_install_file\fR function can be used to inform
the library of the location of the 96000 firmware file
and hence the location of the Octave SCA DSP downloadable.
The standard SCA DSP downloadable is restored when measurements are
begun after selecting \fIoctave_meas\fR of \fBE1432_OCTAVE_MEAS_OFF\fR.

Octave measurements with a trigger_delay, set by \fIe1432_set_trigger_delay\fR,
other than 0 give indeterminate results.

Time and Octave data are related by the trigger condition.
A trigger begins a linear average or an exponential average,
as set by \fIe1432_set_octave_avg_meas\fR.
Since exponential averages run forever, only one trigger is needed
for an exponential average measurement.

\fBNote:\fR If octave_avg_mode is set to exponential, and the measurement
arm mode is set to time arm or rpm arm, the first trigger will start the
measurement and all additional triggers will be ignored.

For linear averages, subsequent triggers are ignored until the time block size,
as set by \fIe1432_set_blocksize\fR,
(minus the overlap, as set by \fIe1432_set_overlap\fR) AND the
integration time, as set by \fIe1432_set_octave_int_time\fR, are fulfilled.
So, if the Time block size (minus overlap) is greater
than the integration time, there will be gaps between the Octave averages.
If the Time block size (minus overlap) is less than the integration time,
then the overlap between Time blocks will be less than specified; there will
be gaps between the time blocks if the Time block size is less than the
integration time.

For exponential averages and updates on linear averages,
as set by \fIe1432_set_octave_time_step\fR,
a time block is chosen to fit the Octave update rate,
so the Time blocks may be overlapped or have gaps between them,
regardless of what the overlap is set to.
This is one case where more than one time block is available for one trigger.

Peak and RMS values are placed in the trailer when Octave measurements are
running and available via \fIe1432_get_current_value\fR calls.
The trailer Peak and RMS values are "filtered", the equivalent of
\fIe1432_get_current_value\fR at for the frame of octave data that they
are attached to.
There is no equivalent of \fBE1432_PEAK_MODE_BLOCK\fR or
\fBE1432_RMS_MODE_BLOCK\fR.

The Octave SCA DSP downloadable is installed in the course of execution
of this function.  Since it temporarily uses memory in the module which
is also used for the arbitray source data, this function must preceed the
function calls to pre-load the arbitrary source buffers using
\fIe1432_write_srcbuffer_data\fR.

Octave measurements reduce the maximum fifo size by up to a factor of 4
and require a significant amount of fifo in order to operate correctly.
Because of this, it is strongly recommended that the fifo size, as set by
\fIe1432_set_fifo_size\fR, be left at its default maximum
when making Octave measurements.

Note that RPM armed measurements can cause incomplete, corrupt linear
averages to be output if the time between RPM points is less than the
update rate.
In this case, the gap field in the header should be examined to insure
a complete, non-corrupted average has been received.
The gap is in samples at the sample_clock of 65536.

.SH "RESET VALUE"
After a reset, \fIoctave_meas\fR is set to \fBE1432_OCTAVE_MEAS_OFF\fR.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.SH "SEE ALSO"
.na
e1432_set_octave_mode,
e1432_set_octave_avg_mode,
e1432_set_octave_hold_mode,
e1432_set_octave_start_freq, e1432_set_octave_stop_freq,
e1432_set_octave_int_time,
e1432_set_octave_time_const,
e1432_set_octave_time_step,
e1432_octave_ctl,
e1432_get_octave_blocksize,
e1432_get_current_data,
e1432_set_trigger_delay,
e1432_install_file
.ad
